Shareware Grab Bag/Shareware Grab Bag.iso/081/sirius50.arc/SIR050D.ARC/SIRIUS.DOC

Text File | 1987-07-14 | 19KB | 435 lines

                 Sirius Fido-compatible Message Base Manager
                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                           Version 0.50 (07/13/87)

          (C) COPYRIGHT 1986,87 by Micro Solutions, Wilmington DE;
              ALL RIGHTS RESERVED


                *********************************************
                *                                           *
                *  MISCELLANEOUS  R-O-U-G-H  DOCUMENTATION  *
                *   (Remember, Sirius is still FREE ... )   *
                *                                           *
                *********************************************


             I. Installation
            II. Major Design Goals
           III. Examples:  Notation and Assumptions
            IV. Scripts
             V. Command Stacking
            VI. Identifying Yourself
           VII. Message Base Navigation
          VIII. Working With Message Groups
            IX. Customizing Sirius Menus
             X. Sirius Update Philosophy
            XI. Trouble-shooting
           XII. Helping Me Help You
          XIII. Where's the Beef?


   #######
   #  I. #  Installation
   #######

   Sirius is distributed in 4 archives as follows:

        SIR050E.ARC     Executables & Overlays
        SIR050D.ARC     Documentation
        SIR050S.ARC     Scripts
        SIR050M.ARC     Menu Customizer

   To install Sirius, you must perform the following steps:

   1. Unbundle the archives into the directory of your choice.  This may be
      the home directory of  your BBS/Mailer, but it  does not have to  be.
      Note  that  Sirius  must  be  RUN  from your favorite critter's home,
      though.

      The installation directory need not be in your DOS search path.

   2. Define the environment variable  SIRIUS to point to  the installation
      directory.  For example, if you installed the files into C:\SIR, then
      you would issed the DOS command:

           SET SIRIUS=C:\SIR

      For more information on environment variables, see your DOS reference
      manual.

   3. There are  two files  distributed with  Sirius which  you must  edit,
      using any text  editor.  The first,  SIRIUS.SIR, is a  Sirius command
      script which is exectued every time Sirius is run.  It is typical  to
      include common startup commands in this file.  For now, all you  need
      to do is modify the shipped version to include your name in the "You"
      command; see the file itself for details.

      The  second  file  you  need  to  modify  is  SIRIUS.CFG,  the Sirius
      configuration file.  Follow the comments in the file in order to make
      changes to the shipped version as appropriate.

   4. Set your default directory to  be the home directory of  your message
      system, if you  are not already  there.  For example,  if you run  an
      Opus CBCS, then  this directory is  probably "C:\OPUS", so  you would
      issue the DOS commands:

           C:
           CD \OPUS

      For more information on the  directory or drive change commands,  see
      your DOS reference manual.

   5. If you have been using an earlier version of Sirius, then you  should
      delete  the  Sirius  area  table  file, SIRIUS.ART.  Sirius 0.50 will
      build a new one for you automatically.

   6. You are now ready to get  started.  If you are new to  Sirius, before
      doing  anything  else  please  run  the Sirius introductory demo.  In
      particular, please execute  the demo option  to send a  HELLO message
      back to me, Bob Klahn, on Opus 150/1 in Wilmington Delaware.  You may
      invoke the introductory demo from DOS by typing:

           SIRIUS INTRO

   7. Documentation archive SIR050D.ARC contains  (a) a set of  incremental
      release notes,  one file  for each  major release  of Sirius, and (b)
      online   help   files   SIRIUS.HLP,   SIRBODY.HLP,   SIRCTRL.HLP, and
      SIREXPR.HLP.  File SCRIPTS.DOC in script archive SIR050S.ARC provides
      a quick overview of all distributed scripts.

      Please BE SURE  TO READ ALL  OF THESE.  I  suggest that you  actually
      print them  and keep  them handy  as you  are learning  to use Sirius
      effectively.  Formal documentation, long awaited, is in the works!


   ########
   #  II. #  Major Design Goals ("Where are we heading?")
   ########

   Sirius must be  a general-purpose Fido-/Opus-/SEAdog-compatible  message
   base manager,  with the  designed-in potential  for becoming  a bulletin
   board itself.

   Sirius  must  give  its  licensees  as  much  "other-board  mobility" as
   possible: the abilities

        (a) To migrate to other Bulletin Board Systems without losing one's
            message or user base, and
        (b) to run  more than one  BBS  at a  time,  with  relatively  free
            information flow between them.

   WHATEVER Sirius does, it must do:

        (1) locally,
        (2) remotely, AND
        (3) from batch files.  It must be possible  to create  these  batch
            files  using  Sirius itself,  simply  by turning  on "learn" or
            "record" mode  and doing  whatever;  these  batch files must be
            flat ASCII, readily understandable to the observer.

   Sirius must automate as many of the BBS sysop's message-related tasks as
   possible.

   But the highest motivation for all of this is to move towards systems in
   which  INFORMATION  CONTENT  and  INFORMATION  FLOW  have MUCH MORE of a
   cause-and-effect relationship than they do today.


   #########
   #  III. #  Examples:  Notation and Assumptions
   #########

   DOUBLE-quotes (") in the examples here serve to clarify only, and should
   never be keyed in.

   SINGLE-quotes (')  function as  character string  delimiters, and should
   ALWAYS be keyed in.

   Unless  stated  otherwise  here,  Sirius  is  assumed to be installed in
   subdirectory "C:\SIR".


   ########
   #  IV. #  Scripts
   ########

   Sirius  can  run  completely  unattended  (e.g.,  as a Fido- or Opus- or
   SEAdog-scheduled external event) by taking its directions from  "batched
   command input files",  or SCRIPTS.  These  command files are  flat ASCII
   text files, designed to  be completely SELF-DOCUMENTING.  You  may (ill-
   advisedly) create them using your favorite text editor, or (a far better
   choice) have Sirius create them for you.

   To create, or "record", a Sirius script: simply key "!R" followed by  an
   optional ENTER,  then specify  the 1-  to 8-character  filename of  your
   choice; terminate the recording process with a second "!R".

   To use  (execute, invoke,  run, ...),  or "play",  a Sirius  script, key
   "!P".  Sirius  will then  ask "Fast  <Y,n>?".  Press  ENTER or  Y (i.e.,
   answer  YES)  to  see  as  little  detail  as  possible;  press N to see
   everything  you  would  normally  see  if  you were keying the script in
   "live".

   Sirius reminds you that it  is recording commands by prefixing  "{R}" to
   each  command  line;  similarly,  a  "{P}"  prefix indicates that Sirius
   script playback is in progress.

   You will  want to  activate the  script recording  process not  only for
   subsequent playback, but  also simply to  record everything that  you do
   during a Sirius session.  Such an "audit trail" serves very  effectively
   as a  review mechanism  and learning  tool, MOST  ESPECIALLY in  helping
   Micro Solutions track down alleged bugs (fleas?).

   You may also invoke Sirius scripts  from the DOS command line.  Thus  if
   Sirius has been installed in subdirectory "C:\SIR", then "SIRIUS  INTRO"
   will perform a "!   (Play ('C:\SIR\INTRO.SIR'))" (note the  default file
   extension).  "SIRIUS SIRDEMO1 SIRDEMO2" will invoke  C:\SIR\SIRDEMO1.SIR
   and  run  it   to  completion,  then   do  the  same   with  the  script
   C:\SIR\SIRDEMO2.SIR.  Scripts invoked from DOS are automatically run  in
   "fast" mode.

   There are  a number  of sample  Sirius scripts  provided in  the archive
   SIR050S.ARC.  File SCRIPTS.DOC describes what each of the sample scripts
   does, and in some cases gives useful pointers in writing your own Sirius
   scripts.  The  files contained  in this  archive will  all help show the
   kinds of things that you can do with the Sirius scripting language,  and
   how you might go about doing them.


   #######
   #  V. #  Command Stacking
   #######

   You will often want to disable menu playback temporarily.  For  example,
   you probably don't need to review area descriptions and path names  each
   time you select a message area.  You won't need to see the QUIT menu  to
   know how to "return to the BBS home directory" more than once or twice.

   From the keyboard, simply key  the first characters of all  commands you
   need no help with, one  after another, before pressing the  <Enter> key.
   Such "abbreviated"  keyboard input  results in  the similary abbreviated
   terminal output you desire.

   E.g., from the main menu, "A2H" will select message area #2 (assuming it
   exists!) and then display that area's highest-numbered message.

   Or, after selecting the  MOVE command from the  main menu, you can  type
   "AN99G"  to  have  Sirius  attempt  to  move the current message to your
   NetMail area, renumbered there as message #99.

   Occasionally  an  "inter-command  separator"  must  be  keyed  to  avoid
   ambiguity or misinterpretation.  Either the  COMMA or the SPACE bar  may
   be used as an inter-command separator.

   Thus,  to  display  messages  #42  and  #45  in the current area with no
   intervening prompts, you must key "42,45" or "42 45".

   You  may  also  disable  menu  playback  from the DOS command line.  For
   example, to go directly to a display of the highest-numbered message  in
   your netmail area, enter "SIRIUS 'ANH'" at the DOS prompt.

   You may combine script names and command stacks on the DOS command line.
   Thus "Sirius 'AN' PRINTNEW" will invoke Sirius, go to the NetMail  area,
   then invoke "C:\SIR\PRINTNEW.SIR", which presumably (if it's the  script
   we supply) sends all not-received  messages in your netmail area  to the
   printer.

   Clearly  there  are  many  ways   to  accomplish   the  same  objective.
   "SIRIUS  'AN!PPRINTNEW'"  and  "SIRIUS  'AN'  PRINTNEW" are functionally
   equivalent, but of the two,  the latter formulation should be  preferred
   because of its greater clarity.


   ########
   #  VI. #  Identifying Yourself
   ########

   The main-menu "You" command identifies "you" to Sirius.  If you want  to
   "be" a particular person, you can change identities without exiting  and
   reinvoking.  This  is especially  handy when  performing a  mixed set of
   tasks  within  a  single  Sirius  session.   E.g.,  in replying to local
   messages,  you  may  want  to  be  "Sysop",  but it's more personal when
   sending netmail to be "Bob Klahn" (at least for ME). Until (and  perhaps
   after!) you  invoke the  "You" command,  you are  anonymous; this is the
   natural choice  for many  unattended operations.   As you  would expect,
   when Sirius knows who you are it can fill in "who" fields during message
   creation: "From" during message  Entry, and "To: during  message Replies
   in which you are the first  or second party.  (See also SIR_043.DOC  for
   alias support.)


   #########
   #  VII. #  Message Base Navigation
   #########

   Sirius message base  navigation differs from  Fido, Opus, and  SEAdog in
   several respects:

        * Sirius keeps track of the low  as well as the high message number
          in each message area.

        * When  you   revisit  a  message  area  during  the  same session,
          Sirius  repositions  at the message  you last visited within that
          area.

        * When you press  the <Enter> key,  Sirius attempts to  continue in
          one of  FOUR directions  of travel:  "Next" (the start-of-session
          default), "Previous",  "+link", or  "-link".  For  example, after
          first  keying  "-"  to  see  the  previous message in the current
          message CHAIN, repeated presses of the <Enter> key will  continue
          backward  along  the  message  CHAIN.   And  if you press <Enter>
          during message display,  display of the  current message BODY  is
          aborted, thereby  allowing fairly  rapid scanning  of the message
          base (see also "Group Headers" in another DOC file).

        * When  the  "end  of  the  path"  is reached, Sirius automatically
          reverses direction.

        * When the  direction of  travel is  "N" or  "P", Sirius skips over
          messages which do not belong to the active message GROUP (if any;
          see "WORKING WITH MESSAGE GROUPS").  When the direction of travel
          is "+" or "-", every message in the chain can be displayed.

        * Whenever you perform an area  change, the direction of travel  is
          reset to "N".

   Can this flow be improved?  What do YOU think?  Send me some FidoMail on
   the subject.


   ##########
   #  VIII. #  Working With Message Groups
   ##########

   Sirius  allows  you  to  define  a  logical message group as being those
   messages which satisfy a  given conditional expression.  A  large number
   of  boolean,  integer,  and  string  functions  along  with   relational
   operators  provide  the  basis  for  the expression definition language.
   There may be up to 26  group definitions known to Sirius (identified  by
   the letters A to  Z), but only ONE  group definition is in  force at any
   given time (this will be expanded in future Sirius versions).

   A group  definition may  be used  in one  of two  ways.  First,  a group
   definition may be  used as a  RETRIEVAL FILTER.  When  an explicit group
   definition is in force, the current message area appears to contain only
   those  messages  which  satisfy  the  group  definition.   The  relative
   positioning commands Next  and Previous will  skip over messages  not in
   the  group,  and  commands  such  as  Group  Headers  will likewise only
   consider those message.

   The  second  use  for  group  definitions  is  in  the  context of group
   operations (most of which are not yet implemented) which will allow  you
   to perform operations on  an entire group of  messages as a single  unit
   (such as  deleting, moving,  copying, etc...).   However, you  may still
   perform operations such as this on an entire message group from within a
   script, so the planned group  operations are more of a  convenience than
   providing  something  not  currently  possible.   See  file SIR_050.DOC,
   sections I and  II, for details  on expressions and  functions used, and
   for more detail on the group definition facility in general.  Note  that
   the same  expression language  is used  in forming  Sirius If  and While
   conditions.


   ########
   #  IX. #  Customizing Sirius Menus
   ########

   Sirius menu customization requires that you have SIRMENU.COM and one  or
   more  SOURCE  menu  files.   Download  SIR_050M.ARC from 150/1 to obtain
   these.


   #######
   #  X. #  Sirius Update Philosophy
   #######

   In general, I will issue a new version when

        (a) I think significant new functionality has been added, or
        (b) another Sirius user  WANTS something (s)he knows I've added, or
        (c) I know  it's going to be a while  before I can add any more, or
        (d) two months  have passed  AND  all SIGNIFICANT  known bugs  have
            been squashed.

   Note: Due to  the MAJOR enhancements  in version 0.50,  this version has
   been four months in development, but such is not the norm.


   ########
   #  XI. #  Trouble-shooting
   ########

   If Sirius ever tells you that it cannot find one of its overlays  (files
   SIR050-1.CHN through SIR050-7.CHN),  verify that the  Sirius environment
   variable  exists  and  points  to  the  subdirectory in which Siriius is
   installed.  If it is, then consider rebooting and trying again.


   #########
   #  XII. #  Helping Me Help You
   #########

   I look  to all  of you  PRIMARILY for  feedback on  CONCEPTS and  on the
   continuing DEVELOPMENT PATH; bug reporting is secondary.  MAKE SURE that
   you:

      * ASK FOR EVERYTHING that you can  think of that you might EVER  want
        in a product which bills itself as a "Fido-compatible message  base
        manager".

      * PRIORITIZE what you ask for.  I am very flexible about the order in
        which things get done.  Sirius features will be added (or at  least
        considered) as YOU ask for them.

      * TELL ME  WHAT YOU  DON'T LIKE,  or WHAT  YOU WOULD  DO DIFFERENTLY.
        There are  an infinite  number of  BETTER ideas  out there  in Idea
        Space.

      * REPORT ANY BUG by  file-attaching the Sirius script  file (produced
        using "!R filename") which reproduces the command sequence  leading
        to the bug.  For example, way  back in Sirius version 0.21, if  you
        attempted to  edit a  body line  which did  not exist, menu\program
        synchronization failed, and Sirius quit.
        The message to  which you attach  this script file  should indicate
        anything about the bug which  the script could not record,  such as
        details of YOUR equipment configuration (make, model, memory, TSR's
        present, DOS  version, ...  ) or  message base  structure (multiple
        disk drives, message counts, chain structure, ... ).

      * COMMUNICATE with me REGULARLY  and FREQUENTLY.  After all,  THAT is
        what THIS is all about!

      * FEEL FREE to help me improve the documentation!  That includes  the
        currently  unindexed  on-line  help  file SIRIUS.HLP; its structure
        should be apparent.


   ##########
   #  XIII. #  Where's the Beef?
   ##########

   We recognize that this introductory document is a bit lacking.  However,
   there is a wealth of information to be found in the incremental  release
   notes files (especially SIR_050.DOC) and in the file SCRIPTS.DOC, not to
   mention in  the sample  scripts themselves.   The need  for complete and
   formal  documentation  is  being  addressed;  the next release of Sirius
   should give you a LOT more to sink your teeth into.

   In  the  mean  time,  it  is  a  good  idea  to join the SIRIUS echomail
   conference, if you have not  already.  See file SIR_ECHO.LST for  a list
   of participating nodes as of this writing.  If you have trouble locating
   a place to link in, drop a note to me (Bob Klahn) on 150/1 and I'll  see
   if I can help get you  connected.  The fastest way to resolve  a problem
   is almost always to drop a note into this echo.





       ---------------------------------------------------------------
       Bob Klahn, OpusNode 150/1:  [phone]   300/1200/2400 baud
       ---------------------------------------------------------------